In thomasgaquiere/Maria: Simulate Different Forms of Logging on a Forest

Introduction

This document aim to give guidelines for all users interested in participating to the development of RconTROLL for both core development or development associated to additional specific modules of TROLL. This document is a work in progress and everybody is invited to participate to its writing using subsequent guidelines. Part of the document is inspired from R packges book by Hadley Wickham and GitHub help, which I recommend to read too.

NB: Those guidelines might be sometimes specific to RconTROLL and may differ for other R packages.

Package structure

RconTROLL R package has the following structure:

• Root files
  • README.md package markdown description
  • NEWS.md news tracking in markdown (see [Version tracking])
  • DESCRIPTION R package description
  • NAMESPACE R package namespace
  • cran-comment.md CRAN submission file
  • .travis.yml, appveyor.yml continuous integration files (see [Social coding with GitHub])
  • RconTROLL.Rproj R project
  • .gitignore, .Rbuildignore files to be ignored bit Git and Rbuild
  • .Rproj.user, .Rhistory, .RData, .Ruserdata R project files
• R folder: include all R code with one file per function, class, method, data, and package (see [Witting R code in RconTROLL]). Cannot include sub-folders !
• man folder: include all package documentation in Rd automatically built with R files (do not edit by hand, see [Documenting])
• inst/extdata folder: include raw data from the package used for examples (init, species, climate, inventory)
• tests folder: include formal tests (see [Formal testing])
• vignettes folder: include package vignettes for users
• docs folder: include developers tools and documentation (including the present document)

Basic workflow

Development should follow the following workflow:

1. Code writing in R
2. Documenting
3. Formal testing and checking
4. Repeat previous steps until happy
5. NEWS editing, commit and push
6. And when ready, sharing

Writing R code in RconTROLL

For the moment code writing does not include much rules. Noticeable rules are listed below, feel free to submit others:

• functions names and variables names (not mandatory for variables) follow camel case writing
• functions names always start in lowercase whereas class names start in uppercase
• R files have the name of the object they include (i.e. function.R, CLASS.R)
• R files for methods include the class name after a dot before the .R (i.e. method.CLASS.R)
• try to minimize functions size and complexity by using internal functions
• internal functions name start with a dot (.internal()) and are generally included in the file from the function using it
• try to follow development good practices with goodpractice::goodpractice() function from package goodpractice

Have a look to already existing code for examples knowing it is not always perfect. When developing you can easily quickly try your new implementation with devtools::load_all(".") or CTRL+SHIFT+L within Rstudio which will load the package in your environment.

Documenting

Documenting use the package Roxygen. When writing an object place your cursor at the beginning of the object, and in Rstudio go to Code>Insert Roxygen skeleton or use CTRL+ALT+SHIFT+R. Roxygen code is a special comment starting with #'. More information are available in Whickam book. Principle things to fill are listed below:

• Dependence to other package functions with @include
• Imports used functions from other packages with @import or @importFrom (prefer @importFrom which import only the function and not the whole package for a smaller environment)
• Object name
• Object description
• Objects parameters or attributes with @param
• What the object return with @return
• An example of the object use with @examples
• Reference to similar or associated functions with @seealso
• And finally export the object to user with @export

Additionally you can put:

• details with @details
• references with @references
• and additional section with @section

You do not only need to document functions but:

• functions
• class
• methods
• data
• and eventually the package itself

The package documentation skeleton has been already set in R/RconTROLL.R, feel free too complete while coding/documenting.

Formal testing

Formal testing use the package testthat and has been already setup in RconTROLL. A dummy example on how to write a test is given in tests/testhat/test_example.R. It basically consist in giving instructions and an expected result. Test unit should be small and include as deep as possible in the code (not always a whole function, can be an internal). More information are available in Whickam book. Note that examples writing in documentation are also used as tests (see [Documenting]). To do testing use devtools::test() or CTR+SHIFT+T in Rstudio. Note that checking (both in Rstudio or continuous integration) are also testing the package with formal testing (see [Checking]). Code coverage by test is assessed by coverage in continuous integration and can be seen online.

Checking

As long as you develop you should check that you are not doing mistakes with all previous indicated tools. In addition, to be sure to have a working package in agreement with CRAN policies for publication you should use the formal check within Rstudio Build>Check or CTRL+SHIFT+E. Note that this formal check will be done by continuous integration inside GitHub with Travis-CI and Appveyor (see [Social coding with GitHub]).

Version tracking

RconTROLL comes with version tracking with git software (see the git simple guide). git is already setup you just have to check its installation on your local machine. And you will find a graphical user interface to use it inside Rstduio itself. When you think that you reached a step in your development you can save it by making a new development version. To do that review you change in git user interface by validating them checking the box. Then use the commit button. Add a message and commit. I recommend the message to start with the version, i.e. RconTROLL 0.1.9010 and to give a short information on the new implementations. In parallel update the NEWS.md file by opening a new header with the new version, i.e. # RconTROLL 0.1.9010, and list your changes with stars, i.e. * I made this.

Social coding with GitHub

RconTROLL development rely on a team and if you want your contribution to be included in it you should follow social coding recommendations with GitHub. This section presents the RconTROLL on-line GitHub repository, how to initialize your own development to be connected with others, and how to further develop in agreements with others and share your novelties.

RconTROLL GitHub repository

The official main development branch of RconTROLL is hosted on Fabian Fischer's account at https://github.com/fischer-fjd/RconTroll. You will find here the code with the README to introduce you to the repository.

Development objectives, bugs to fix or suggestions to implement are listed as issues in the issues section. You can either decide to participate in solving one or open a new one that you wish to solve or to get help on it. You can assign people or yourself in solving an issue. You can reference the type of issue. And finally you can relate issues to projects (next paragraph). More on issues are available on GitHub help.

The projects section organised issues into project to realize. There is two types of projects in RconTROLL: (i) the core development of the package including all functions useful for all basic simulations of TROLL, and the module-specific projects related to each developed or under-development modules of TROLL related to specific objectives (i.e. ABC, sylviculture ...). Inside a project issues are organised into sections (e.g. core project):

• Low priority: issues to be discussed or to be dealt with later
• ToDo: issues to be dealt with asap
• InProgress: issues under development
• ToValidate: issues solved and/or developed waiting for package maintainers approval
• Done: issues done and validated

The repository is also organised into branches allowing parallel development of core functions and main team and other branches of more specific unstable modules. Have a look to GitHub help on branches.

Finally, collaborations (so eventually yours) can be followed in the insights section and more particularly the network graph can help understand the current development from the package.

Initialization for your development

If it's the first time you wish to contribute to RconTROLL package please first start to fork the original repository. For that open an account on GitHub if you do not already have one an use the upper right button to fork (see GitHub help on forks).

Then, there is two cases:

• you want to do core-development or development of a project already opened on another branch, in which case you will work either on the main or on the project specific branch
• you want to work on a new project in which case you need to open a new branch on your fork (please consider opening corresponding issues and project on the main repository)

Then you just have to clone locally the repository on your machine with Git using

```{bash, echo=T, eval=F} git clone [e-mail]:your_account/RconTroll.git

and further move in Rstudio on the corresponding branch you want to work on (upper right corner of Git interface in Rstudio) or with Git

```{bash, echo=T, eval=F}
git checkout -b "your_branch_name"

Further development

When you start or continue to develop your local version or your branch you may want to get back parallel developments of the main repository. In order to do that use git fetch as explained in the GitHub help about fetching a repository. You may need to solve conflicts, which is relatively simple and consist in in choosing which recent version you want to keep (either yours or the one from the mane repository, see help).

Then develop your code using advised workflow and recommendations from previous sections. Use the version tracking chapter to update NEWS and commit your changes. You can use cross-reference to cite issues (#Number), projects or people (@poeple) in you NEWS and commit messages.

When you want your changes to be available on your fork online use the push button in Rstudio git user interface or with git push in a command line interface. Pushing your changes online will trigger continuous integration tools: (i) Travis-CI and AppVeyor will do a check of your package similar to CRAN including formal testing and inform you by email if the package is still valid, (ii) covr will inform you the change of package coverage, i.e. if you decreased or increased formal testing coverage of the code, and especially which lines of codes necessitate formal testing.

Once you want to share your code new implementations with the rest of the development team and maintainers to be validated use pull-requests. Pull-requests section is available on the main repository of RconTROLL. Simply open a new one and link it to your on-line fork branch you wish to share. Do not forget to reference the pull request in corresponding issues. More about pull requests is available on GitHub help pages.

Conclusion

I hope those guidelines will help you in further development of your projects inside RconTROLL.

Have a nice development ;)

thomasgaquiere/Maria documentation built on Dec. 24, 2021, 1:20 a.m.